MINED				EDITOR				MINED


NAME
    mined - a text editor

SYNTAX
    mined [ -<options> ] [ +linenumber ] [ filename ] [ more filenames ... ]


DESCRIPTION
    An easy-to-use and natural in appearance text editor.
    Its original version was designed for Andrew S Tanenbaum's operating 
    system Minix.

    Startup features:
	- with given file name (as usual) or multiple file names
	- without given file name
	- reading from a pipe (reading text from standard input)
	- writing into a pipe (writing edited text to standard output)
    Examples:
	mined x		- edits the file x
	mined x y z	- edits files x, y, and z
	cmd | mined	- edits the output of "cmd", file name for saving 
			  can be given later
	mined x > y	- takes the contents of file x and edits it 
			  for writing into y
	mined | mail nn	- edits a text to be mailed
	cmd1 | mined | cmd2 - modifies text in between a pipe from 
				program cmd1 (output) to cmd2 (as input)
    Startup options:
	+number	Mined positions to the given line number.
	-v	Mined starts in view only mode. The text cannot be modified.
	-m	ESC ESC does not exit mined, but proceed to the next file.
		(currently default setting)
	-p	Enables provisions for proportional display fonts. (I have 
		not yet encountered a terminal emulation which handles this 
		well, see comments in mined.new.)
	-r	Ignore CR characters (so strip them at line ends).
		I.e., read MSDOS text on Unix machines.
	-R	Take CR only for newline. I.e., read MacIntosh text on 
		MSDOS or Unix machines.
	-C	Enables use of Chinese or other 16-bit character set. A byte 
		with high bit set is regarded as the first of a two-byte 
		character sequence and will not be separated in certain 
		mined operations. This works well, e.g., with the Chinese 
		xterm version, cxterm.
	-B	Backspace deletes left, Delete deletes right.
	-W	Select WordStar key function layout. This includes many 
		functions of the ^K, ^O, and ^Q menus.
	-s	Display option: Stay with cursor in top line after page down 
		or bottom line after page up instead of center line.
	-S	Display option: Use scrolling for page up/down.
	-dn	Display option: Apply delay between lines of page output to 
		achieve nice effective display build-up, starting from the 
		new cursor position proceeding to the screen edges.
		If n lies between '0' and '9', the respective number of 
		milliseconds is applied between display of two lines.
		If n='0', still an output flush is performed.
		If n='-', no delay at all is applied though still the order 
		of display output is from cursor position to edges.
		Default: '-' in the Unix version, '9' in the MSDOS version.
		To achieve paging speed at the keyboard repeat rate but still 
		have a taste of the build-up effect, a value of '5' or '6' 
		is suitable on my MSDOS system.
    These options are also looked for in the environment variable MINED.
    Some options can also be set by the existence of further variables:
	MINEDPROP	sets -p
	MINEDCHIN	sets -C
	MINEDMAC	sets -R
	MINEDWS		sets -W

  Basic functionality
    Mined is always in insert mode. Commands are single control characters, 
    double key commands starting with ESCAPE, and a collection of function 
    keys (currently installed for the VT220, SUN, and Iris terminals). 
    As a specialty, note the prefixing 'HOP KEY' which stretches the effect 
    of some cursor and screen motion commands just as you would expect; this 
    provides for more command flexibility without too much key remembering. 
    Control key layout in the current version is 'geographically' oriented 
    on the left side of the keyboard for the main motion commands, an idea 
    probably originating from the 'WordMaster' and 'WordStar' editors. 
    On SUN terminals, also the right-hand cursor block is assigned the 
    most important movement functions as follows:
                        +------+-------+------+
                        | LnDn |   ^   | PgUp |
                        +------+-------+------+
                        |  <-  |  HOP  |  ->  |
                        +------+-------+------+
                        | LnUp |   v   | PgDn |
                        +------+-------+------+

    Note that line-feeds (end-of-line character) are treated like any 
    ordinary character except that they cannot occur in search strings.
    This drawback (not to be able to search / replace lineends naturally) 
    seems to be a tradition of line-oriented unix tools and I was not 
    willing to spend that much time going into very special parts of mined.

    Every care has been taken to prevent loss of the edited text in case 
    of save errors or accidental quit commands etc. Also, if a command is 
    given to write to a file not previously read in, mined prompts for 
    confirmation.
    In the "write to standard output" mode, only one save to standard output 
    can be performed, so there is a problem in the case that more than one 
    saving actions occur; the first save (whether by a write, edit, 
    or suspend command) of the buffer is written to standard output, 
    any subsequent one is treated as usual (with empty file name).

    Before regarding the command keys and their functions, 
    note the following general remarks:

  The HOP function
    This function, triggered by any of the HOP keys, fortifies (or modifies) 
    functions as follows. To achieve the combined function, first press 
    any key that is assigned the HOP function, then any key assigned 
    the second function:

    HOP - char left			move cursor to start of current line
    HOP - char right			move cursor to end of current line
    HOP - line up			move cursor to top of screen
    HOP - line down			move cursor to bottom of screen
    HOP - scroll up			scroll half a screen up
    HOP - scroll down			scroll half a screen down
    HOP - page up			move to start of file
    HOP - page down			move to end of file
    HOP - word left			move cursor to previous ";" or "."
    HOP - word right			move cursor to next ";" or "."
    HOP - delete tail of line/lineend	delete whole line
    HOP - delete whole line		delete tail of line
    HOP - delete previous character	delete beginning of line
    HOP - set mark			go to mark
    HOP - search			search for current identifier
    HOP - search next			repeat previous (last but one) search
    HOP - copy/cut			copy or cut, but append to buffer
    HOP - save buffer			save buffer, but append to file
    HOP - paste buffer			paste "inter-window buffer", 
			which is the last saved buffer by any invocation 
			of mined on the same machine by the same user.
    HOP - edit next file		edit last file
    HOP - edit previous file		edit first file
    HOP - suspend			suspend without writing file

  Typing in 8-bit characters in absence of appropriate keyboard
    Some function keys can be used as prefix keys to change the character 
    assigned to the following key to a diacritic or special character.
    (MSDOS remark: the prefix and compose functions have been defined as 
    appropriate for the "Codepage" 850. Some of the characters shown below 
    are meaningless as letters in the "default Codepage" 437.)

    Six diacritic prefix functions are provided:
    grave: adds grave accent where applicable: àèìòù ╖╘▐πδ
	R1 (sun)
	shift-F6 (pc)
    circumflex: adds circumflex accent where applicable: âêîôû ╢╥╫ΓΩ
	R2 (sun)
	cntrl-F6 (pc)
    acute: adds acute accent where applicable: áéíóú∞ ╡É╓αΘφ
	R3 (sun)
	F6 (pc)
    diaeresis: adds diaeresis where applicable: äëïöüÿ Ä╙╪ÖÜ
	R4 (sun)
	F7 (pc)
	F6 (vt100)
    tilde: adds tilde where applicable: ╞ñΣ ╟Ñσ
	R5 (sun)
	shift-F7 (pc)
    angstrom: a»å, A»Å, e»æ, E»Æ, o»¢, O»¥
	R6 (sun)
	cntrl-F7 (pc)
    Where these rules do not apply, any of these prefix keys makes the 
    following default transformations:
	s»ß, c»ç, C»Ç, n»ñ, N»Ñ, d»╨, D»╤, p»τ, P»Φ, m»µ,
	l»£, L»£, /»╜, $»╜, Y»╛, X»╧, &»⌠, #»⌡, !»¡, ?»¿,
	<»«, >»», x»₧, :»÷, +»±, 0»°, 1»√, 2»², 3»ⁿ,
	*»*, .»·, ,»≈, "»", '»∩, _»ε, -»≡, \»¬, |»▌

    In addition, the enter-control-code prefix (^V (WS: ^P)) has been 
    extended to compose characters if the first following key typed in 
    is a character resembling an accent mark ("'`^°~). The accent 
    is placed on the second character keyed in or the default diacritic 
    transformation applied to it.

    If you have an appropriate keyboard, you can of course also type in 
    any 8-bit character directly or using the Compose/Combine key.


  Summary of mined commands
  =========================
   Alternative commands or functions keys are listed in further lines 
   with an indentation for better orientation.

  Cursor and screen motion
  ------------------------
   ^E			Move cursor 1 line up
	up-arrow
   ^X			Move cursor 1 line down
	down-arrow
   ^S ^H		Move cursor 1 character left
			^H can also be set to delete left
	left-arrow
   ^D			Move cursor 1 character right
	right-arrow
   ^A			Move backward to start of previous word
	Ctrl-left (MSDOS)
   ^F			Move forward to start of next word
	Ctrl-right (MSDOS)
   ^R			Scroll backward 1 page (Top line becomes bottom line)
	PrevScreen (vt100)
	PgUp (R9, sun)
	PgUp (MSDOS)
   ^C			Scroll forward 1 page (Bottom line becomes top line)
	NextScreen
	PgDn (R15, sun)
	PgDn (MSDOS)
   ^W			Scroll screen backward 1 line
	PF2 (vt100)
	Home (R7, sun)
	Ctrl-PgUp (MSDOS)
   ^Z			Scroll screen forward 1 line
	PF3 (vt100)
	End (R13, sun)
	Ctrl-PgDn (MSDOS)
   ^Gnn			Move to a line (prompts for line number)
   ^Gnn%		Move to position in text determined by percentage
	if ^G is not immediately followed by a digit, it works as HOP key 
	for the following command if applicable.
   ESC g		Goto line/percentage/Hop (same as ^G)
   ESC ]    ^G ^]	Move to the position previously marked by ^]

   ^Q			HOP key
	^G	(if not followed by a digit)
	PF1 (vt100)
	"5" (R11, sun)
	"5" (MSDOS)
	F10 (MSDOS)
	ESC (especially MSDOS, not recommended as an alternative HOP key 
		where function keys may start with ESC)

   On terminals or windows which can transform mouse button pressings into 
   key sequences, direct positioning on the current screen is also available:
	(e.g. crttool)
   left button		position only
   middle button	position and set mark (^] (WS: ^K^B) command)
   right button		position and copy text (^Y (WS: ^K^K^K^C) command)

  Modifying text
  --------------
   <printable char>  Insert the character, 
   <RET or LF char>  linefeed (newline), 
   <TAB char>	     or tab at cursor position
   ^V <char>	     Enter control character (also in prompted input)
   ^O		     Make new line at current position
   <DEL char>	     Delete previous character
		     <DEL> can also be set to delete right (next character)
   ^B		     Delete next character
   ^T		     Delete next word
   ^^		     Delete previous word
   ^K		     Delete tail of line; if at end of line, delete linefeed

   ESC X	Replace current character with its hexadecimal representation.
   ESC O	Replace current character with its octal representation.
   ESC D	Replace current character with its decimal representation.
   ESC j	("Justify") Format paragraph by word-wrapping according to 
		the currently set left and right margin values.
   ESC <	Set left margin for justification.
   ESC >	Set right margin for justification.

  Text block and buffer operations
  --------------------------------
   ^]			Set mark (to remember the current location)
	Select (vt100)
	Stop (L1, sun)
	Pos1 (MSDOS)
   ^U			Cut text between and current position; save in buffer
	Remove (vt100)
	Cut (L10, sun)
	Ctrl-End (MSDOS)
   ^Y			Copy text between mark and current position into buffer
	Do (vt100)
	Copy (L6, sun)
	End (MSDOS)
   ^P			Paste contents of buffer to current position
	InsertHere (vt100)
	Paste (L8, sun)
	Ins (sun)
	Ins (MSDOS)
   ESC b		Copy contents of buffer into a file
   ESC i		Insert file at current position
   ESC p		Print contents of buffer (to default printer)
   ESC c		Perform command (prompted for) with buffer as input
	For modifications of the "cut", "copy", "paste" and 
	"copy buffer to file" commands by the HOP function see above.

  Search
  ------
   ESC /  Find	Search forward (prompt for regular expression)
	F8 (sun)
	F8 (MSDOS)
   ESC \	Search backward (prompt for regular expression)
   ^N		Search for next occurence (previous expression and direction)
	Find (vt100)
	Find (L9, sun)
	F9 (sun)
	F9 (MSDOS)
   ESC s	(Global) Substitute str1 by str2 (prompts for each string)
   ESC r	(Global) Replace str1 by str2 with confirmation prompting
   ESC R	(Line Replace) Substitute string1 by string2

  Special functions in a search string:
	.	matches any character.
	^	(at begin of pattern) restricts match to the begin of a line.
	$	(at end of pattern) restricts match to the end of a line.
	[<cset>] matches any one of a set of characters;
		the set may be given by listing elements,
		denoting a range <c1>-<c2>,
		or negating the whole set [^<cset>].
	\<c>	matches character <c> literally.
	<pat>*	where <pat> is any one of the defined patterns,
		matches a (zero or more times) repetition of this pattern.
  Special function in a replacement string:
	&	is replaced by the matched pattern to be replaced.


  Miscellaneous
  -------------
   ESC w	Save (write back) current text to file (only if modified).
   ESC W	Save (write back) current text to file (unconditionally).
   ESC e	Edit another file (prompt for save if current text changed).
   ESC v	View another file (prompt for save if current text changed).
   ESC q	Quit the editor (prompt for save if current text changed).
   ESC ESC	Exit editing current text (save first if changed), continue 
		with next file if multiple files were specified.
   ESC +	Edit the next file in the list of file names.
   ESC -	Edit the previous file in the list of file names.
   ESC #	Ask for index into the list of file names and edit that file.
   ESC = count	Repeat a command count times (prompts for count).
   ESC count	Repeat a command count times (prompts for rest of count).
   ^\		Abort current command (also while prompting or searching).
   ESC ?	Print the current status of the file.
   ESC d	Show working directory / change to another one.
   ESC n	Change file name associated with edited text (does not 
		affect the text currently being edited, just detaches it 
		from the file previously read in).
   ESC .	Redraw the screen.
   ESC z	Suspend editor process; first write back file if modified
		(no write if HOPped or given empty file name on prompting).
   ESC !	Fork off a shell and wait for it to finish.
   ESC h	Show (this) help file.
	Help (vt100 / sun)

   ESC		While a command is active and prompting, aborts the 
		current command.
   ESC ' '	(Escape Blank) Do nothing, so blank aborts the ESC command.

   F1		\
   shift-F1	 \ (MSDOS) Show function key menu line.
   control-F1	 / Function key assignments are not completely listed above.
   alt-F1	/

   When entering file names, the leading ~/ notation is accepted.

  MSDOS only:
   ESC m	Change video mode to the mode with the next smaller 
		total resolution (lines * columns). This depends on a 
		table contained in the source file minedmp.c. Since there 
		exists font/mode substitution software for MSDOS which 
		may change font style along with screen size, the actual 
		change effective may occasionally be unexpected.
   ESC M	Change video mode to the mode with the next higher 
		total resolution.
   ESC l	Change video lines mode to the mode with the next smaller 
		number of lines but same number of columns. The previous 
		remark holds as well so this command may even have less 
		expected results than ESC m/M (e.g., using VGAMAX).
		Actually the number of lines is first tried to be 
		decreased within the current video mode, if it is lowest, 
		the next video mode is chosen.
   ESC L	Change video lines mode to the mode with the next higher 
		number of lines but same number of columns.
   HOP ESC m/M/l/L	Several other video mode settings (experimental).
   Alt-F9 / Ctrl-F9	Switch between highest and lowest / 
			circle through all line number modes within 
			the current basic screen mode.

ENVIRONMENT
  Concerning some especially stupid terminal drivers /
  Enabling soft handshake
    If there is a need to ignore ^S and ^Q keys (in case of stupid keyboard 
    drivers which use them, but don't filter them out), the environment 
    variable NoCtrlSQ or NoControlSQ must be set. The tty channel soft 
    handshake setting will then also not be disabled in case this would 
    affect remote connection behaviour.

  Help display selection
    Mined looks up the environment variable PAGER or uses 'more' for showing 
    the help file. The complete command to show it can be changed by setting 
    the environment variable MINEDHELP (e.g. to 'less .../mined.help').
    A "%s" within the MINEDHELP variable will be replaced by the directory 
    mined was started from.

  Print direction
    The environment variable MINEDPRINT may contain a print command to be 
    used instead of the default (which is operating system dependant). The 
    variable must contain the string %s in the place for the filename.

  Line contents indications
    Lines which are too long for the screen are usually indicated by a 
    '»' or '>' character. This can be changed by setting the environment 
    variable MINEDSHIFT. If this variable contains a second character, 
    that one will be used to indicate lines shifted out left off the screen. 

    If an environment variable MINEDRET is set, its contents (one character) 
    is placed as an indicator at the end of every text line on screen.
    If MINEDRET contains another character it is used to fill the rest of 
    the screen lines, leaving out the position for the MINEDSHIFT mark, 
    which can however be filled with a third character from MINEDRET.
    I recommend to set MINEDRET to '«' for people who want to see line ends 
    or '«·' (or '···' or '··«') for people who like Siemens terminals.
    Try also '«°', '«∙' (MSDOS), and others.

    If visible display of TAB characters is desired, the environment 
    variable MINEDTAB can be set (e.g. to '·').

  Buffer file names
    For the paste buffer, the inter-window paste buffer, and the panic file, 
    environment information as usual on the respective operating system is 
    used to build the names. (Unix: TMPDIR, USER; VMS: SYS$SCRATCH, SYS$LOGIN, 
    USER; MSDOS: TEMP, TMP)

  Terminal type
    The Unix terminal type is determined from the environment variable TERM.

  Highlight mode (MSDOS only)
    The ANSI codes for selecting normal and exposed display can be chosen 
    with the environment variable MINEDCOL. The two selections are separated 
    by a space. Each selection is a semicolon-separated list of the code 
    values. The default behaviour corresponds to the setting 
	set MINEDCOL=7 27
    Example: Green on red text, red on green status: set MINEDCOL=34;42 32;44

More special MSDOS notes:
    To make use of the cursor block "5" key which is very practical to 
    hold the fortifying HOP function, you will have to use either an 
    enhanced keyboard driver (or an appropriate Bios) or a suitable 
    keyboard extension TSR program (e.g., ENHKBD.COM). The usual PC 
    keyboard drivers are so ignorant to forbid you to use that key.

    The default colour setting depends on an extended ANSI driver 
    (like NNANSI) as does the scroll down function anyway. Unfortunately, 
    there is no way to find out the current colour setting nor is there an 
    inverse video mode in many ANSI drivers (only a fixed black on white 
    mode) so that it is impossible to implement just inverse display for 
    highlighting. Therefore, if mined thinks to see an ANSI driver of the 
    simpler kind, it will change its colour setting defaults. In any case, 
    these can be overridden with the MINEDCOL variable.

    Mined finds out the current screen size on startup.

    Mined tries to analyse the ANSI drivers capabilities by checking the 
    control sequences for colour setting, line insert/delete. This 
    already depends, however, on the ANSI driver's ability to send 
    cursor position reports. If it cannot do that, a faked pseudo-report 
    should be stuffed into mined as its first input (with some key-stuffing 
    program) and mined will use no further cursor position requests. It 
    will also assume a simple ANSI driver then. The faked report should 
    consist of the screen size in lines and columns, embedded at the 
    positions of the ANSI cursor report sequence but with different 
    surrounding characters. For an invocation of mined on a 25 lines and 
    80 columns screen a batch file for this would look like:
	keypress xx25x80xx
	mined %1 %2 %3 %4 %5 %6 %7 %8 %9

    PCDOS has this well-hated memory limitation which limits the size of 
    editable files to currently ca. 300K at an average line length of ca. 
    50 characters, ca. 500K can be loaded with all lines of maximal length, 
    and down to ca. 200K with short lines of ca. 20 characters.
    Compilation with a compiler making use of extended memory would probably 
    remove this problem.
    Moreover, with Turbo-C, I experienced the effect that mined uses about 
    twice the amount of memory as would be expected (length of lines plus 
    13/16 bytes per line). This is also not very nice. Can someone help?

DIAGNOSTICS
    In all cases where it is considered sensible, the appropriate message 
    of a system error occurred is displayed (instead of printing numerical 
    hieroglyphs or indistinguished commonplace messages as many other 
    UNIX commands do).

BUGS
    When lines are shifted on the display while moving around in a very 
    small window, positioning errors and display garbage may occur. This 
    bug has probably been extinguished except when less than 8 character 
    columns can be displayed in the window.

    Mined always completes the last text line with a newline when it 
    writes back the file even if there was none before.

    (Unix:) Mined cannot edit a pipe file and hangs if you try to do so. 
    (But it can insert from, or write to, a pipe and is interruptable 
    by ^\ then.)
    Mined can neither edit nor insert or write to device files such as tty.

    (MSDOS:) Pipe input does not work. I don't know why.

    (MSDOS:) Typing of control-P while display output is active (i.e., 
    during screen paging) can hang the system. Typing of control-C or 
    control-Break while display output is active can at least leave some 
    garbage on the screen. Typing of control-P, control-C, or control-Break 
    while a search operation is active can be desastrous. Can anyone please 
    tell me how to disable BIOS/MSDOS interpretation of these characters 
    from Turbo-C?

FILES
  Unix:
    /usr/man/catl/mined.l		This help file
    $TMPDIR/minedbuf.USER.PID.NN	Temporary file for buffer
    $TMPDIR/minedbuf.USER		File for inter-window buffer
    $TMPDIR/minedpanic.USER.PID		Panic file to rescue text before crash
	If $TMPDIR is not available, /tmp is used.
  VMS:
    SYS$SCRATCH:$MINEDBUF$user.pid.nn	Buffer
    SYS$SCRATCH:$MINEDBUF$user		Inter-window buffer
    SYS$SCRATCH:$MINEDPANIC$user.pid	Panic file
	If SYS$SCRATCH is not available, SYS$LOGIN is used instead.
  MSDOS:
    %TEMP%\minedbuf.nn		Buffer
    %TEMP%\minedbuf		Inter-window buffer
    %TEMP%\mined-pa.nic		Panic file
	If %TEMP% is not available, %TMP% or \ are used.

COMMENTS and IMPROVEMENT SUGGESTIONS
    wolff@inf.fu-berlin.de
